home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 43 / Amiga Format CD43 (1999)(Future Publishing)(GB)(Track 1 of 2)[!][issue 1999-09].iso / -serious- / programming / mui / mcc_pkb / developer / autodocs / mcc_pkb.doc
Text File  |  1999-06-14  |  11KB  |  522 lines
  1. TABLE OF CONTENTS
  2.  
  3. Pkb.mcc/Pkb.mcc
  4. Pkb.mcc/MUIA_Pkb_Mode
  5. Pkb.mcc/MUIA_Pkb_AutoRelease
  6. Pkb.mcc/MUIA_Pkb_Current
  7. Pkb.mcc/MUIA_Pkb_Quiet
  8. Pkb.mcc/MUIA_Pkb_Pool
  9. Pkb.mcc/MUIA_Pkb_PoolPuddleSize
  10. Pkb.mcc/MUIA_Pkb_PoolThreshSize
  11. Pkb.mcc/MUIA_Pkb_Octv_Name
  12. Pkb.mcc/MUIA_Pkb_Octv_Base
  13. Pkb.mcc/MUIA_Pkb_Octv_Range
  14. Pkb.mcc/MUIA_Pkb_Octv_Start
  15. Pkb.mcc/MUIA_Pkb_Key_Release
  16. Pkb.mcc/MUIA_Pkb_Key_Press
  17. Pkb.mcc/MUIA_Pkb_Range_Head
  18. Pkb.mcc/MUIA_Pkb_Range_Start
  19. Pkb.mcc/MUIA_Pkb_Range_End
  20. Pkb.mcc/MUIA_Pkb_Low
  21. Pkb.mcc/MUIA_Pkb_High
  22. Pkb.mcc/MUIM_Pkb_Reset
  23. Pkb.mcc/MUIM_Pkb_Refresh
  24. Pkb.mcc/MUIM_Pkb_Range
  25. Pkb.mcc/MUIM_Pkb_Range_Reset
  26. Pkb.mcc/MUIM_Pkb_Range_Refresh
  27. Pkb.mcc/MUIM_Pkb_Jump
  28. Pkb.mcc/MUIA_Pkb_InputEnable
  29. Pkb.mcc/MUIA_Pkb_ExcludeLow
  30. Pkb.mcc/MUIA_Pkb_ExcludeHigh
  31. Pkb.mcc/MUIA_Pkb_Type
  32. Pkb.mcc/Pkb.mcc
  33.  
  34.    Pkb is a Custom Class of the Magic User Interface © by Stefan Stuntz.
  35.    It's a subclass of Virtgroup-class.
  36.  
  37.    The aim of this class is to provide a piano keyboard for generic music
  38.    applications.
  39.  
  40.    Pkb uses different colours for the different working modes, and they
  41.    can be changed by the user through MCP.
  42.  
  43.    Please have a look at the example program for further details.
  44.  
  45.    The demo can be compiled with Dice or StormC 2.0.
  46.  
  47. NOTES
  48.    None at the moment.
  49.  
  50. Pkb.mcc/MUIA_Pkb_Mode
  51.  
  52. NAME
  53.    MUIA_Pkb_Mode   -- (V14.3) [ISG], ULONG
  54.  
  55. FUNCTION
  56.    Sets or returns keyboard's operating mode.
  57.  
  58. INPUTS
  59.    MUIV_Pkb_Mode_NORMAL   (default)
  60.    MUIV_Pkb_Mode_SPECIAL
  61.    MUIV_Pkb_Mode_RANGE
  62.  
  63. NOTES
  64.    The first two modes only differ for what regards the colour used for
  65.    depressed keys.
  66.  
  67.    The third mode is used to mark a group of contiguous keys.
  68.    The MUIA_Pkb_Range_Start and MUIA_Pkb_Range_End attributes respectively
  69.    provide the start and the end key of the LAST selected group.
  70.    In this mode the MUIA_Pkb_Key_Release attribute is NOT set when the
  71.    user releases the mouse on the last key.
  72.  
  73. SEE ALSO
  74.    MUIA_Pkb_Range_Head
  75.  
  76. Pkb.mcc/MUIA_Pkb_AutoRelease
  77.  
  78. NAME
  79.    MUIA_Pkb_AutoRelease   -- (V14.3) [ISG], BOOL
  80.  
  81. FUNCTION
  82.    Sets or detects the automatic key release.
  83.  
  84. INPUTS
  85.    -TRUE  (default)
  86.    -FALSE
  87.  
  88. NOTES
  89.    If it is TRUE, the key is released when the user presses another key.
  90.    If it is FALSE, the key is not released, and its release is up to the
  91.    application.
  92.  
  93. SEE ALSO
  94.    MUIA_Pkb_Key_Press , MUIA_Pkb_Key_Release
  95.  
  96. Pkb.mcc/MUIA_Pkb_Current
  97.  
  98. NAME
  99.     MUIA_Pkb_Current   -- (V14.3) [..GN], LONG
  100.  
  101. FUNCTION
  102.    Detects the code of the last note played (the last key pressed) by the
  103.    user.
  104.  
  105. NOTES
  106.    The return code ranges between 0 and 131 and is independent of the
  107.    octave number that could be shown on the bottom bar.
  108.  
  109. SEE ALSO
  110.    MUIA_Pkb_Octv_Start, MUIA_Pkb_Octv_Range, MUIA_Pkb_Key_Release
  111.  
  112. Pkb.mcc/MUIA_Pkb_Quiet
  113.  
  114. NAME
  115.    MUIA_Pkb_Quiet   -- (V14.3) [.S.], BOOL
  116.  
  117. FUNCTION
  118.    If it is set to TRUE then no keys are drawn.
  119.  
  120. SEE ALSO
  121.     MUIM_Pkb_Refresh
  122.  
  123. Pkb.mcc/MUIA_Pkb_Pool
  124.  
  125. NAME
  126.    MUIA_Pkb_Pool   -- (V14.3) [I.G], PoolHeader *
  127.  
  128. FUNCTION
  129.    Pass something from CreatePool() here if you don't want the table
  130.    to create its own memory pool but to use this one instead. Note
  131.    that pkb group class does *not* use semaphore protection when
  132.    accessing the pool, you must *not* use pools which are
  133.    accessed from other tasks than the application's main
  134.    task.
  135.  
  136. SEE ALSO
  137.     MUIA_Pkb_PoolPuddleSize, MUIA_Pkb_PoolThreshSize
  138.  
  139. Pkb.mcc/MUIA_Pkb_PoolPuddleSize
  140.  
  141. NAME
  142.    MUIA_Pkb_PoolPuddleSize   -- (V14.3) [I..], ULONG
  143.  
  144. FUNCTION
  145.    Specify the puddle size for the tables memory pool.
  146.  
  147.    Defaults to 2048. It is ignored if you specify your
  148.    own pool with MUIA_Pkb_Pool.
  149.  
  150. SEE ALSO
  151.     MUIA_Pkb_Pool, MUIA_Pkb_PoolThreshSize
  152.  
  153. Pkb.mcc/MUIA_Pkb_PoolThreshSize
  154.  
  155. NAME
  156.    MUIA_Pkb_PoolThreshSize   -- (V14.3) [I..], ULONG
  157.  
  158. FUNCTION
  159.     Specify the thresh size for the tables memory pool.
  160.  
  161.     Defaults to 1024. It is ignored if you specify your
  162.     own pool with MUIA_Pkb_Pool.
  163.  
  164. SEE ALSO
  165.     MUIA_Pkb_Pool, MUIA_Pkb_PoolPuddleSize
  166.  
  167. Pkb.mcc/MUIA_Pkb_Octv_Name
  168.  
  169. NAME
  170.    MUIA_Pkb_Octv_Name   -- (V14.3) [I..], BOOL
  171.  
  172. FUNCTION
  173.    Indicates whether a bar will be shown below the keyboard.
  174.  
  175. SEE ALSO
  176.  
  177.  
  178. Pkb.mcc/MUIA_Pkb_Octv_Base
  179.  
  180. NAME
  181.    MUIA_Pkb_Octv_Base   -- (V14.3) [I..], LONG
  182.  
  183. FUNCTION
  184.    Indicates the starting number that will be shown on the bar below the
  185.    keyboard.
  186.  
  187. NOTES
  188.    Beware: key codes are NOT affected by the octave number shown on the
  189.    bar.
  190.  
  191. SEE ALSO
  192.     MUIA_Pkb_Octv_Name
  193.  
  194. Pkb.mcc/MUIA_Pkb_Octv_Range
  195.  
  196. NAME
  197.    MUIA_Pkb_Octv_Range   -- (V14.3) [I...], ULONG
  198.  
  199. FUNCTION
  200.    Indicates how many octaves will be shown on the keyboard.
  201.    Accepted values: 1...11
  202.  
  203. SEE ALSO
  204.  
  205.  
  206. Pkb.mcc/MUIA_Pkb_Octv_Start
  207.  
  208. NAME
  209.    MUIA_Pkb_Octv_Start   -- (V14.3) [I.G], ULONG
  210.  
  211. FUNCTION
  212.    Indicates the starting octave for the keyboard.
  213.  
  214. NOTES
  215.    Beware: MUIA_Pkb_Octv_Start + MUIA_Pkb_Octv_Range MUST be <= 11,
  216.    otherwise MUIA_Pkb_Octv_Start will be automatically decreased until the
  217.    condition is satisfied.
  218.  
  219. SEE ALSO
  220.  
  221.  
  222. Pkb.mcc/MUIA_Pkb_Key_Release
  223.  
  224. NAME
  225.     MUIA_Pkb_Key_Release   -- (V14.3) [.S.N], ULONG
  226.  
  227. FUNCTION
  228.    Releases a key.
  229.  
  230. NOTES
  231.    The code ranges between 0 and 131 and is independent of the
  232.    octave number that could be shown on the bottom bar.
  233.  
  234. SEE ALSO
  235.    MUIA_Pkb_Octv_Start, MUIA_Pkb_Octv_Range, MUIA_Pkb_Key_Press
  236.  
  237. Pkb.mcc/MUIA_Pkb_Key_Press
  238.  
  239. NAME
  240.     MUIA_Pkb_Key_Press   -- (V14.3) [.S..], ULONG
  241.  
  242. FUNCTION
  243.    Presses a key.
  244.  
  245. NOTES
  246.    The code ranges between 0 and 131 and is independent of the
  247.    octave number that could be shown on the bottom bar.
  248.  
  249. SEE ALSO
  250.    MUIA_Pkb_Octv_Start, MUIA_Pkb_Octv_Range, MUIA_Pkb_Key_Release
  251.  
  252. Pkb.mcc/MUIA_Pkb_Range_Head
  253.  
  254. NAME
  255.    MUIA_Pkb_Range_Head   -- (V14.3) [.SGM], ULONG
  256.  
  257. FUNCTION
  258.    Sets or returns the group leader in range mode.
  259.  
  260. INPUTS
  261.    MUIV_Pkb_Range_Head_OFF
  262.    MUIV_Pkb_Range_Head_BOT
  263.    MUIV_Pkb_Range_Head_TOP
  264.  
  265. SEE ALSO
  266.    MUIA_Pkb_Mode
  267.  
  268. Pkb.mcc/MUIA_Pkb_Range_Start
  269.  
  270. NAME
  271.    MUIA_Pkb_Range_Start   -- (V14.3) [.SGM], LONG
  272.  
  273. FUNCTION
  274.    Sets or returns the code of the lowest note in the LAST active range.
  275.  
  276. NOTES
  277.    When setting, you have to provide a valid positive value.
  278.  
  279.    Getting this attribute you are always returned a value ranging between
  280.    0 and 131, or -1 if there is no active range.
  281.  
  282. SEE ALSO
  283.    MUIA_Pkb_Range_End, MUIA_Pkb_Mode
  284.  
  285. Pkb.mcc/MUIA_Pkb_Range_End
  286.  
  287. NAME
  288.    MUIA_Pkb_Range_End   -- (V14.3) [.SGM], LONG
  289.  
  290. FUNCTION
  291.    Sets or returns the code of the highest note in the LAST active range.
  292.  
  293. NOTES
  294.    When setting, you have to provide a valid positive value.
  295.  
  296.    Getting this attribute, you are always returned a value ranging between
  297.    0 and 131, or -1 if there is no active range.
  298.  
  299. SEE ALSO
  300.    MUIA_Pkb_Range_Start, MUIA_Pkb_Mode
  301.  
  302. Pkb.mcc/MUIA_Pkb_Low
  303.  
  304. NAME
  305.    MUIA_Pkb_Low   -- (V14.3) [..G.], ULONG
  306.  
  307. FUNCTION
  308.    Returns the code of the lowest note in the keyboard.
  309.  
  310. SEE ALSO
  311.    MUIA_Pkb_High
  312.  
  313. Pkb.mcc/MUIA_Pkb_High
  314.  
  315. NAME
  316.    MUIA_Pkb_High   -- (V14.3) [..G.], ULONG
  317.  
  318. FUNCTION
  319.    Returns the code of the highest note in the keyboard.
  320.  
  321. SEE ALSO
  322.    MUIA_Pkb_Low
  323.  
  324. Pkb.mcc/MUIM_Pkb_Reset
  325.  
  326. NAME
  327.    MUIM_Pkb_Reset
  328.  
  329. SYNOPSIS
  330.    DoMethod(obj, MUIM_Pkb_Reset);
  331.  
  332. FUNCTION
  333.    Resets the keyboard by releasing all keys.
  334.  
  335. SEE ALSO
  336.  
  337.  
  338. Pkb.mcc/MUIM_Pkb_Refresh
  339.  
  340. NAME
  341.    MUIM_Pkb_Refresh  -- (V14.3)
  342.  
  343. SYNOPSIS
  344.    DoMethod(obj, MUIM_Pkb_Refresh);
  345.  
  346. FUNCTION
  347.    Refreshes the keyboard.
  348.  
  349. NOTES
  350.    This method can be useful if some changes have been made while the
  351.    keyboard had MUIA_Pkb_Quiet set to TRUE.
  352.  
  353. SEE ALSO
  354.    MUIA_Pkb_Quiet
  355.  
  356. Pkb.mcc/MUIM_Pkb_Range
  357.  
  358. NAME
  359.    MUIM_Pkb_Range  -- (V14.3)
  360.  
  361. SYNOPSIS
  362.    DoMethod(obj, MUIM_Pkb_Range, ULONG nstart, ULONG nend);
  363.  
  364. FUNCTION
  365.    Creates a range between the nstart and nend values.
  366.  
  367. NOTES
  368.    The nstart value doesn't necessarily need to be lower than nend, but
  369.    they both have to be in the 0...131 range.
  370.  
  371. SEE ALSO
  372.    MUIA_Pkb_Range_Start, MUIA_Pkb_Range_End
  373.  
  374. Pkb.mcc/MUIM_Pkb_Range_Reset
  375.  
  376. NAME
  377.    MUIM_Pkb_Range_Reset  -- (V14.3)
  378.  
  379. SYNOPSIS
  380.    DoMethod(obj, MUIM_Pkb_Range_Reset);
  381.  
  382. FUNCTION
  383.    Resets the LAST active range, so releasing all the keys which formed
  384.    it.
  385.  
  386. NOTES
  387.    After calling this method the MUIA_Pkb_Range_Start and
  388.    MUIA_Pkb_Range_End attributes are reset.
  389.  
  390. SEE ALSO
  391.    MUIA_Pkb_Range_Start, MUIA_Pkb_Range_End
  392.  
  393. Pkb.mcc/MUIM_Pkb_Range_Refresh
  394.  
  395. NAME
  396.    MUIM_Pkb_Range_Refresh  -- (V14.3)
  397.  
  398. SYNOPSIS
  399.    DoMethod(obj, MUIM_Pkb_Range_Refresh);
  400.  
  401. FUNCTION
  402.    Refreshes the active range, that is, the group of notes which are
  403.    included between MUIA_Pkb_Range_Start and MUIA_Pkb_Range_End.
  404.  
  405. SEE ALSO
  406.    MUIA_Pkb_Range_Start, MUIA_Pkb_Range_End
  407.  
  408. Pkb.mcc/MUIM_Pkb_Jump
  409.  
  410. NAME
  411.    MUIM_Pkb_Jump  -- (V14.3)
  412.  
  413. SYNOPSIS
  414.    DoMethod(obj, MUIM_Pkb_Jump, ULONG ncode);
  415.  
  416. FUNCTION
  417.    Jumps to the note corresponding to the ncode code, thus making it
  418.    visible.
  419.  
  420. NOTES
  421.    The ncode value must necessarily be included amongst the ones provided
  422.    by the keyboard, that is, between MUIA_Pkb_Low and MUIA_Pkb_High.
  423.  
  424. SEE ALSO
  425.    MUIA_Pkb_Range_Start, MUIA_Pkb_Range_End
  426.  
  427. Pkb.mcc/MUIA_Pkb_InputEnable
  428.  
  429. NAME
  430.    MUIA_Pkb_InputEnable   -- (V14.4) [ISG], BOOL
  431.  
  432. FUNCTION
  433.    Enables or disables user interaction with the keyboard.
  434.  
  435. INPUTS
  436.    TRUE   (default)
  437.    FALSE
  438.  
  439. NOTES
  440.      Set this attribute if you want to prevent the keyboard from reacting to
  441.      user's mouse clicks, so that it doesn't receive any event.
  442.  
  443.      When setting the MUIA_Pkb_Quiet tag to TRUE, the keyboard SEEMS not
  444.      to react, because keys are not updated, but attributes depending on
  445.      lowering and raising of keys - like MUIA_Pkb_Key_Release,
  446.      MUIA_Pkb_Key_Press etc. - are actually updated.
  447.  
  448. SEE ALSO
  449.    MUIA_Pkb_Quiet
  450.  
  451. Pkb.mcc/MUIA_Pkb_ExcludeLow
  452.  
  453. NAME
  454.    MUIA_Pkb_ExcludeLow   -- (V14.4) [ISG], ULONG
  455.  
  456. FUNCTION
  457.    Sets or returns the number of halftones excluded from the lowest part of
  458.    the keyboard. 
  459.  
  460. INPUTS
  461.         0 : no keys excluded  (default)
  462.    1...11 : excludes C...Bb
  463.  
  464. NOTES
  465.    The Pkb class CANNOT draw incomplete octaves.
  466.    Anyway, sometimes you need to have a keyboard which starts with a note
  467.    different from the typical C.
  468.    You can obtain this by setting MUIA_Pkb_ExcludeLow to the proper
  469.    number of halftones.
  470.    The excluded keys will be drawn anyway, but they will have a different
  471.    colour and they will not have any effect.
  472.  
  473. SEE ALSO
  474.    MUIA_Pkb_ExcludeHigh
  475.  
  476. Pkb.mcc/MUIA_Pkb_ExcludeHigh
  477.  
  478. NAME
  479.    MUIA_Pkb_ExcludeHigh   -- (V14.4) [ISG], ULONG
  480.  
  481. FUNCTION
  482.    Sets or returns the number of halftones excluded from the highest part of
  483.    the keyboard.
  484.  
  485. INPUTS
  486.         0 : no keys excluded  (default)
  487.    1...11 : excludes B...Db
  488.  
  489. NOTES
  490.    The Pkb class CANNOT draw incomplete octaves.
  491.    Anyway, sometimes you need to have a keyboard which ends with a note
  492.    different from the typical B.
  493.    You can obtain this by setting MUIA_Pkb_ExcludeHigh to the proper
  494.    number of halftones.
  495.    The excluded keys will be drawn anyway, but they will have a different
  496.    colour and they will not have any effect.
  497.  
  498. SEE ALSO
  499.    MUIA_Pkb_ExcludeLow
  500.  
  501. Pkb.mcc/MUIA_Pkb_Type
  502.  
  503. NAME
  504.    MUIA_Pkb_Type   -- (V14.6) [I.G], ULONG
  505.  
  506. FUNCTION
  507.    Indicates the keyboard type.
  508.  
  509. INPUTS
  510.    MUIV_Pkb_Type_NORMAL  (default)
  511.    MUIV_Pkb_Type_SMALL
  512.  
  513. NOTES
  514.    The standard 105x50 pixels size of an octave can sometimes be excessive,
  515.    depending on the particular application or the screen size. In such
  516.    cases, or when the programmer feels like doing it, MUIA_Pkb_Type can be
  517.    set to MUIV_Pkb_Type_SMALL to obtain a reduced 70x39 pixels size for the
  518.    octave.
  519.  
  520. SEE ALSO
  521.  
  522.